bitkeeper revision 1.1108.33.3 (410817b8l8iY5hb257vj-ECAksWmhA)
authormwilli2@equilibrium.research.intel-research.net <mwilli2@equilibrium.research.intel-research.net>
Wed, 28 Jul 2004 21:16:40 +0000 (21:16 +0000)
committermwilli2@equilibrium.research.intel-research.net <mwilli2@equilibrium.research.intel-research.net>
Wed, 28 Jul 2004 21:16:40 +0000 (21:16 +0000)
Tweaks + incorporate text from the existing README file.
There's quite a lot of relevant information in here now, although
there's still some way to go.

docs/user.tex

index e380bf7b3993b4c8c9392565350547ac645003a0..112fc42f0df1b13e76c2eb1ac11d79885445e3a8 100644 (file)
@@ -76,13 +76,28 @@ Xen support is available for increasingly many operating systems.  The
 following OSs have either been ported already or a port is in
 progress:
 \begin{itemize}
+\item Dragonfly BSD
+\item FreeBSD 4.8
 \item Linux 2.4
 \item Linux 2.6
-\item FreeBSD 4.8
 \item NetBSD 2.0
 \item Plan 9
+\item Windows XP
 \end{itemize}
 
+Right now, Linux 2.4 and 2.6 are available for on Xen 2.0 (the
+modifications to Linux are distributed with Xen).  The NetBSD port
+will be updated to run on Xen 2.0, hopefully in time for the Xen 2.0
+release.  Even running multiple copies of the same OS can be very
+useful, as it provides a means of containing faults to one OS image,
+and also for providing performance isolation between the various OS,
+enabling you to either restrict, or reserve resources for, particular
+VM instances.  It is intended that Xen support be integrated into the
+official releases of Linux 2.6, NetBSD 2.0, FreeBSD and Dragonfly.
+
+The Windows XP port is only available to those who have signed the
+Microsoft Academic Source License.
+
 Possible usage scenarios for Xen include:
 \begin{description}
 \item [Kernel development] test and debug kernel modifications in a
@@ -98,6 +113,10 @@ Possible usage scenarios for Xen include:
       machine-specifics and load balance using live migration
 \item [High availability computing] run device drivers in sandboxed
       domains for increased robustness
+\item [Hardware support for custom OSes] export drivers from a
+      mainstream OS (e.g. Linux) with good hardware support
+      to your custom OS, avoiding the need for you to port existing
+      drivers to achieve good hardware support
 \end{description}
 
 \section{Structure}
@@ -138,8 +157,71 @@ system kernels must explicitly support Xen in order to run in a
 virtual machine, { \em user space applications and libraries
 do not require modification }.
 
-\subsection{History}
-
+\section{Hardware Support}
+
+Xen currently runs on the x86 architecture, but could in principle be
+ported to others. In fact, it would have been rather easier to write
+Xen for pretty much any other architecture as x86 is particularly
+tricky to handle. A good description of Xen's design, implementation
+and performance is contained in the October 2003 SOSP paper, available
+at:
+{\tt http://www.cl.cam.ac.uk/netos/papers/2003-xensosp.pdf}
+Work to port Xen to x86\_64 and IA64 is currently underway.
+
+Xen is targetted at server-class machines, and the current list of
+supported hardware very much reflects this, avoiding the need for us
+to write drivers for "legacy" hardware. It is likely that some desktop
+chipsets will fail to work properly with the default Xen
+configuration: specifying {\tt noacpi} or {\tt ignorebiostables} when
+booting Xen may help in these cases.
+
+Xen requires a ``P6'' or newer processor (e.g. Pentium Pro, Celeron,
+Pentium II, Pentium III, Pentium IV, Xeon, AMD Athlon, AMD Duron).
+Multiprocessor machines are supported, and we also have basic support
+for HyperThreading (SMT), although this remains a topic for ongoing
+research. We're also working on an x86_64 port (though Xen should
+already run on these systems just fine in 32-bit mode).
+
+Xen can currently use up to 4GB of memory.  It is possible for x86
+machines to address up to 64GB of physical memory but (unless an
+external developer volunteers) there are no plans to support these
+systems.  The x86\_64 port is the planned route to supporting more
+than 4GB of memory.
+
+In contrast to previous Xen versions, in Xen 2.0 device drivers run
+within a privileged guest OS rather than within Xen itself. This means
+that we should be compatible with the majority of device hardware
+supported by Linux.  The default XenLinux build contains support for
+relatively modern server-class network and disk hardware, but you can
+add suppport for other hardware by configuring your XenLinux kernel in
+the normal way (e.g. \verb_# make ARCH=xen xconfig_).
+
+\section{History}
+
+
+``Xen'' is a Virtual Machine Monitor (VMM) originally developed by the
+Systems Research Group of the University of Cambridge Computer
+Laboratory, as part of the UK-EPSRC funded XenoServers project.
+
+The XenoServers project aims to provide a ``public infrastructure for
+global distributed computing'', and Xen plays a key part in that,
+allowing us to efficiently partition a single machine to enable
+multiple independent clients to run their operating systems and
+applications in an environment providing protection, resource
+isolation and accounting.  The project web page contains further
+information along with pointers to papers and technical reports:
+{\tt http://www.cl.cam.ac.uk/xeno}
+
+Xen has since grown into a project in its own right, enabling us to
+investigate interesting research issues regarding the best techniques
+for virtualizing resources such as the CPU, memory, disk and network.
+The project has been bolstered by support from Intel Research
+Cambridge, and HP Labs, who are now working closely with us. We're
+also in receipt of support from Microsoft Research Cambridge to port
+Windows XP to run on Xen.
+
+Xen was first described in the 2003 paper at SOSP
+({\tt http://www.cl.cam.ac.uk/netos/papers/2003-xensosp.pdf}).
 The first public release of Xen (1.0) was made in October 2003.  Xen
 was developed as a research project by the University of Cambridge
 Computer Laboratory (UK).  Xen was the first Virtual Machine Monitor
@@ -150,7 +232,10 @@ scenarios on multiple sites.
 
 Xen 2.0 is the latest release, featuring greatly enhanced hardware
 support, configuration flexibility, useability and a larger complement
-of supported operating systems.
+of supported operating systems.  We think that Xen has the potential
+to become {\em the} definitive open source virtualisation solution and
+will work to conclusively achieve that position.
+
 
 \chapter{Installation}
 
@@ -204,8 +289,9 @@ line.
 
 \subsection{Using Bitkeeper}
 
-The public master BK repository for the 2.0 release lives at:
-{\tt bk://xen.bkbits.net/xeno-unstable.bk}.
+The public master BK repository for the 2.0 release lives at: \\
+{\tt bk://xen.bkbits.net/xeno-unstable.bk}.  You can use Bitkeeper to
+download it and keep it updated with the latest features and fixes.
 
 Change to the directory in which you want to put the source code, then
 run:
@@ -226,6 +312,13 @@ changes to the repository by running:
 # bk pull             # to update the repository
 \end{verbatim}
 
+\subsection{Without Bitkeeper}
+
+The Xen source tree is also available in gzipped tarball form from the
+Xen downloads page:\\
+{\tt http://www.cl.cam.ac.uk/Research/SRG/netos/xen/downloads.html}.
+Prebuilt tarballs are also available but are very large.
+
 \section{The distribution}
 
 The Xen source code repository is structured as follows:
@@ -256,27 +349,63 @@ following:
       unprivileged virtual machines.
 \end{itemize}
 
-\begin{verbatim}
-# make world
-\end{verbatim}
-
-To build the unprivileged port of Linux 2.6, do:
-\begin{verbatim}
-# make linux26
-\end{verbatim}
+Inspect the Makefile if you want to see what goes on during a
+build. Building Xen and the tools is straightforward, but XenLinux is
+more complicated. The makefile needs a `pristine' linux kernel tree
+which it will then add the Xen architecture files to. You can tell the
+makefile the location of the appropriate linux compressed tar file by
+setting the LINUX\_SRC environment variable, e.g. \\
+\verb!# LINUX\_SRC=/tmp/linux-2.4.26.tar.gz make world! \\
+or by placing
+the tar file somewhere in the search path of LINUX_SRC_PATH which
+defaults to ".:..". If the makefile can't find a suitable kernel tar
+file it attempts to download it from kernel.org (this won't work if
+you're behind a firewall).
+
+After untaring the pristine kernel tree, the makefile uses the {\tt
+mkbuildtree} script to add the Xen patches the kernel. It then builds
+two different XenLinux images, one with a ``-xen0'' extension which
+contains hardware device drivers and is intended to be used in the
+first virtual machine (``domain 0''), and one with a ``-xenU''
+extension that just contains virtual-device drivers.
+
+The procedure is similar to build the Linux 2.6 port: \\
+\verb!LINUX\_SRC=/path/to/linux2.6/source make linux26!
+
+In both cases, if you have an SMP machine you may wish to give the
+{\tt '-j4'} argument to make to get a parallel build.
 
 The files produced by the build process are stored under the
 \path{install/} directory.  To install them in their default
-locations, do:
-
-\begin{verbatim}
-# make install
-\end{verbatim}
+locations, do: \\
+\verb_# make install_\\
 
 Alternatively, users with special installation requirements may wish
 to install them manually by copying file to their appropriate
 destinations.
 
+Take a look at the files in \path{install/boot/}:
+\begin{itemize}
+\item \path{install/boot/xen.gz} The Xen 'kernel'
+\item \path{install/boot/vmlinuz-2.4.26-xen0}  Domain 0 XenLinux kernel
+\item \path{install/boot/vmlinuz-2.4.26-xenU}  Unprivileged XenLinux kernel
+\end{itemize}
+
+The difference between the two Linux kernels that are built is due to
+the configuration file used for each. The "U" suffixed unprivileged
+version doesn't contain any of the physical hardware device drivers
+--- it is 30\% smaller and hence may be preferred for your
+non-privileged domains.  The ``0'' suffixed privileged version can be
+used to boot the system, as well as in driver domains and unprivileged
+domains.
+
+The \path{install/boot} directory will also contain the config files
+used for building the XenLinux kernels, and also versions of Xen and
+XenLinux kernels that contain debug symbols (\path{xen-syms} and
+\path{vmlinux-syms-2.4.26-xen0}) which are essential for interpreting crash
+dumps.  Retain these files as the developers may wish to see them if
+you post on the mailing list.
+
 \section{Configuration}
 
 \subsection{GRUB Configuration}
@@ -429,6 +558,30 @@ The most important {\tt xm} commands are: \\
 \verb_# xm console_: open a console to a domain.
 e.g. \verb_# xm console 1_ (open console to domain 1)
 
+\subsection{\tt xm list}
+
+The output of {\tt xm list} is in rows of the following format:\\
+\verb_domid name memory cpu state cputime_
+
+\begin{description}
+\item[domid] The number of the domain ID this virtual machine is running in.
+\item[name]  The descriptive name of the virtual machine.
+\item[memory] Memory size in megabytes.
+\item[cpu]   The CPU this domain is running on.
+\item[state] Domain state consists of 5 fields:
+  \begin{description}
+  \item[r] running
+  \item[b] blocked
+  \item[p] paused
+  \item[s] shutdown
+  \item[c] crashed
+  \end{description}
+\item[cputime] How much CPU time (in seconds) the domain has used so far.
+
+The {\tt xm list} command also supports a long output format when the
+{\tt -l} switch is used.  This outputs the fulls details of the
+running domains in SXP format.
+
  XXX More explanation needed here...
 
 \chapter{Other kinds of storage}